<!DOCTYPE html>
<html lang="en">
<head>
	<meta charset="utf-8">
	<title>EasyRTC Documentation</title>
	<link href="assets/easyrtc-docs-styles-1.css" media="all" rel="stylesheet" />
</head>
<body>
<header class="template">
	<div class="wrapper-content">
    <a href="./index.html"><img src="assets/easyrtc-logo.png" alt="EasyRTC Documentation"></a>
		<h1 title="EasyRTC Documentation">Documentation</h1>
	</div>
</header>
<div class="wrapper-docs">
<nav>
	<h2><a href="./index.html">Docs Home</a></h2>
	<h3>EasyRTC Guides</h3>
	<ul>
		<li><a href="easyrtc_faq.html">FAQ</a></li>
		<li><a href="easyrtc_gettingStarted.html">Getting Started</a></li>
		<li><a href="easyrtc_server_install.html">EasyRTC Server: Installation</a></li>
		<li><a href="easyrtc_client_tutorial.html">EasyRTC Framework Tutorial</a></li>
		<li><a href="easyrtc_rooms.html">Rooms</a></li>
		<li><a href="easyrtc_server_configuration.html">EasyRTC Server: Configuration</a></li>
		<li><a href="easyrtc_server_events.html">EasyRTC Server: Events</a></li>
		<li><a href="easyrtc_server_ice.html">EasyRTC Server: ICE Configuration</a></li>
		<li><a href="easyrtc_with_other_servers.html">Using Alongside Other Servers</a></li>
		<li><a href="easyrtc_server_ssl.html">EasyRTC Server: Using SSL</a></li>
		<li><a href="easyrtc_webrtc_problems.html">WebRTC Problems and Possible Fixes</a></li>
		<li><a href="easyrtc_upcoming_features.html">Upcoming Features</a></li>
		<li><a href="easyrtc_changelog.html">Change Log</a></li>
	</ul>

	<h3>EasyRTC Client Classes</h3>
	<ul>
		<li><a href="client-api/Easyrtc.html">Easyrtc</a></li>
		<li><a href="client-api/Easyrtc_App.html">Easyrtc_App</a></li>
		<li><a href="client-api/Easyrtc_ft.html">Easyrtc_ft</a></li>
		<li><a href="client-api/Easyrtc_IframeCapture.html">Easyrtc_IframeCapture</a></li>
		<li><a href="client-api/Easyrtc_No_IframeCapture.html">Easyrtc_No_IframeCapture</a></li>
		<li><a href="client-api/Easyrtc_Rates.html">Easyrtc_Rates</a></li>
		<li><a href="client-api/Easyrtc_Recorder.html">Easyrtc_Recorder</a></li>
	</ul>
	<h3>EasyRTC Server Modules</h3>
	<ul>
		<li><a href="server-api/module-easyrtc_default_event_listeners.html">easyrtc_default_event_listeners</a></li>
		<li><a href="server-api/module-easyrtc_default_options.html">easyrtc_default_options</a></li>
		<li><a href="server-api/module-easyrtc_private_obj.html">easyrtc_private_obj</a></li>
		<li><a href="server-api/module-easyrtc_public_obj.html">easyrtc_public_obj</a></li>
		<li><a href="server-api/module-easyrtc_util.html">easyrtc_util</a></li>
		<li><a href="server-api/module-general_util.html">general_util</a></li>
	</ul>
	<h3>EasyRTC Server Classes</h3>
	<ul>
		<li><a href="server-api/module-easyrtc_default_event_listeners-eventListener.html">eventListener</a></li>
		<li><a href="server-api/module-easyrtc_public_obj-pub.html">pub</a></li>
		<li><a href="server-api/module-easyrtc_public_obj-pub.events.html">events</a></li>
		<li><a href="server-api/module-easyrtc_public_obj-pub.util.html">util</a></li>
		<li><a href="server-api/module-easyrtc_util-eu.html">eu</a></li>
		<li><a href="server-api/module-general_util-g.html">g</a></li>
		<li><a href="server-api/pub.appObj.html">appObj</a></li>
		<li><a href="server-api/pub.appObj.connectionObj.html">connectionObj</a></li>
		<li><a href="server-api/pub.appObj.connectionObj.connectionRoomObj.html">connectionRoomObj</a></li>
		<li><a href="server-api/pub.appObj.roomObj.html">roomObj</a></li>
		<li><a href="server-api/pub.appObj.sessionObj.html">sessionObj</a></li>
	</ul>
</nav>
<div class="easyrtc-docs-content">
<h1>EasyRTC: Rooms</h1>

<h2>EasyRTC Room Features</h2>

<ul><li>Clients can connect to one or more rooms</li><li>Clients can see all other clients in the same room</li><li>Server can restrict who gains access to rooms</li><li>Server can define room fields (variables) which are shared to all clients in a room</li></ul>

<h2>Default Room Behavior</h2>

<ul><li>If no room is specified the client will join a default room named &quot;default&quot;</li><li>Requested rooms will automatically be created if they don&#39;t currently exist</li><li>Clients see all other authenticated clients within the same room</li></ul>

<h2>Server Options which Effect Rooms</h2>

<p><strong>Room Options</strong>
 - roomAutoCreateEnable
   - Enables the creation of rooms from the API. Occurs when client joins a nonexistent room.
   - Defaults to: true
 - roomDefaultEnable
   -  Enables connections joining a default room if it is not initially specified. If false, than a connection initially may be in no room.
   - Defaults to: true
 - roomDefaultFieldObj
   - Default fields which are set when a room is created. In form of {&quot;fieldName&quot;:{fieldValue:&lt;JsonObj&gt;, fieldOption:{isShared:&lt;boolean&gt;}}[, ...]}
   - Defaults to: null
 - roomDefaultName
   - The default room a connection joins if it is not initially specified.
   - Defaults to: &quot;default&quot;</p>

<h2>JavaScript Client API - Joining a room</h2>

<h3>easyrtc.joinRoom()</h3>

<p>Joining a room is handled using the joinRoom function. This can be run before or after <code>easyrtc.connect()</code> or <code>easyrtc.easyApp()</code>. It may be called multiple times to be in multiple rooms simultaneously. It may be called before or after connecting to the server.</p>

<p>Note: the successCB and failureDB will only be called if you are already connected to the server.</p>

<p><strong>Format</strong></p>

<p><code>easyrtc.joinRoom(roomName, roomParameters, successCB, failureCB)</code></p>

<p><strong>Parameters</strong>
 - <strong>roomName</strong> - String. Unique room name
 - <strong>roomParameters</strong> - Can be null. Parameters set here are sent to the server and seen in the <code>roomJoin</code> event.
 - <strong>successCB</strong> - Success callback which expects a function(roomName). May be null. Is only called if client is already connected to the server.
 - <strong>failureCB</strong> - Failure callback which expects a function(errorCode, errorText, roomName). May be null. Is only called if client is already connected to the server.</p>

<h2>JavaScript Client API - Leaving a room</h2>

<h3>easyrtc.leaveRoom()</h3>

<p>Leaving a room is handled using the leaveRoom function, or through disconnecting.</p>

<p><strong>Format</strong></p>

<p><code>easyrtc.leaveRoom(roomName, successCB, failureCB)</code></p>

<p><strong>Parameters</strong>
 - <strong>roomName</strong> - String. Unique room name
 - <strong>successCB</strong> - Success callback which expects a function(roomName). May be null. Is only called if client is already connected to the server.
 - <strong>failureCB</strong> - Failure callback which expects a function(errorCode, errorText, roomName). May be null. Is only called if client is already connected to the server.</p>

<h2>Server - &quot;roomCreate&quot; Event</h2>

<p>When a client has requested to create a room, the &quot;roomCreate&quot; event is fired. By setting a new listener for the &quot;roomCreate&quot; event, the default behavior can be overruled.</p>

<p>Note: The roomCreate event will be fired when a client requests to join a room which doesn&#39;t exist and the &quot;roomAutoCreateEnable&quot; option is set to true. Upon successful callback.</p>

<h3>Common Uses:</h3>

<ul><li>Authenticate who is permitted to create rooms</li><li>Set roomField&#39;s</li><li>Perform application logic, where rooms may be matched to a database entry</li></ul>

<h2>Server - &quot;roomJoin&quot; Event</h2>

<p>Controlling who can join an existing room, and what occurs when joining is controlled by a listener for the &quot;roomJoin&quot; event. By setting a new listener for the &quot;roomJoin&quot; event, the default behavior can be overruled.</p>

<h3>Common Uses:</h3>

<ul><li>Authenticate who is permitted to join rooms</li><li>Set roomField&#39;s</li><li>Control which other clients receive an update that a client joined the room</li><li>Perform application logic, where rooms may be matched to a database entry</li></ul>

<h2>Server - &quot;roomLeave&quot; Event</h2>

<p>When a client has requested to leave a room, the &quot;roomLeave&quot; event is fired. By setting a new listener for the &quot;roomLeave&quot; event, the default behavior can be overruled.</p>

<h3>Common Uses:</h3>

<ul><li>Prevent a client from leaving a room</li><li>Set roomField&#39;s</li><li>Control which other clients receive an update that a client left the room</li><li>Perform application logic, where rooms may be matched to a database entry</li></ul>

<h2>If You Run Into Problems</h2>

<p>Please feel free to post on our discussion forum:</p>

<ul><li><a href="https://groups.google.com/forum/?fromgroups#!forum/easyrtc">https://groups.google.com/forum/?fromgroups#!forum/easyrtc</a></li></ul>

	</div>
</div>
<footer class="template">
	<div class="wrapper-content">
		<p>Copyright &copy;2016 EasyRTC</p>
	</div>
</footer>
</body>
</html>